//+------------------------------------------------------------------+
//|                                            IEqualityComparer.mqh |
//|                             Copyright 2000-2025, MetaQuotes Ltd. |
//|                                             https://www.mql5.com |
//+------------------------------------------------------------------+

//+------------------------------------------------------------------+
//| IEqualityComparer<T> 泛型接口：外部相等性比较器标准接口           |
//| 核心定位：定义独立于对象本身的外部比较器接口，用于判断两个同类型对象的相等性， |
//|           并为对象生成哈希值，支持同一类型的多种相等性判断规则（如订单可按ID或时间比较）|
//| 泛型特性：通过模板参数 <T> 适配任意数据类型，确保比较操作的类型安全性，   |
//|           仅允许同类型对象间的比较（如 T=订单类型时，只能比较两个订单） |
//| 核心价值：作为“外部比较策略”，实现“比较逻辑与对象本身解耦”，同一对象可根据业务场景 |
//|           切换不同的相等性判断规则（如订单在统计时按日期分组，在去重时按ID判断），|
//|           同时为哈希表等数据结构提供灵活的哈希计算逻辑               |
//| 与 IEqualityComparable<T> 的区别：                                |
//|           - IEqualityComparable<T>：对象自身实现相等性判断（内置比较逻辑）；|
//|           - IEqualityComparer<T>：外部比较器实现比较逻辑（可灵活替换）；  |
//|           两者配合可满足多样化的相等性判断需求                       |
//+------------------------------------------------------------------+
template<typename T>
interface IEqualityComparer
  {
   //----------------------------------------------------------------
   // 相等性判断接口：定义两个对象的业务相等规则
   //----------------------------------------------------------------
   /**
    * @brief 判断两个对象在业务逻辑上是否相等
    * @param x [in] 第一个比较对象（类型必须与 T 一致）
    * @param y [in] 第二个比较对象（类型必须与 T 一致）
    * @return bool - 相等性结果：true=业务上相等，false=不相等
    * @note 实现规范：
    *       1. 自反性：x.Equals(x, x) 必为 true
    *       2. 对称性：x.Equals(a, b) 与 x.Equals(b, a) 结果一致
    *       3. 传递性：若 x.Equals(a, b) 和 x.Equals(b, c) 为 true，则 x.Equals(a, c) 必为 true
    *       4. 灵活性：可基于不同业务场景定义比较维度（如订单按ID或开仓日期比较）
    *       5. 空值处理：若 T 为指针类型，需处理 x 或 y 为 NULL 的情况（通常 NULL 与 NULL 相等，与非 NULL 不等）
    */
   bool      Equals(T x, T y);

   //----------------------------------------------------------------
   // 哈希值计算接口：为指定对象生成哈希标识
   //----------------------------------------------------------------
   /**
    * @brief 为指定对象计算哈希值，用于哈希表等数据结构的快速索引
    * @param value [in] 待计算哈希值的对象（类型必须与 T 一致）
    * @return int - 32位哈希值（相同业务对象必须返回相同值）
    * @note 实现规范：
    *       1. 一致性：若 Equals(x, y) 为 true，则 HashCode(x) 必等于 HashCode(y)
    *       2. 分散性：不同对象尽量返回不同哈希值（减少哈希冲突，提升哈希表效率）
    *       3. 场景适配：哈希计算逻辑需与 Equals() 方法的比较维度一致（如按日期比较则基于日期计算哈希）
    *       4. 高效性：计算逻辑需简洁（避免复杂运算影响哈希表操作性能）
    */
   int       HashCode(T value);
  };
//+------------------------------------------------------------------+